Skip to content

fix(sync): Webull trade history without phantom positions - #56

Merged
ChristopherDownie merged 2 commits into
mainfrom
fix/webull-sync
Oct 27, 2026
Merged

ChristopherDownie merged 2 commits into
mainfrom
fix/webull-sync

Conversation

@ChristopherDownie

@ChristopherDownie ChristopherDownie commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Webull sync now imports trade history without inventing positions, using broker-sdk 0.6.0 (#28). It replaces #29 with our own implementation.

Cause

broker-sdk 0.6.0 reads a year of Webull order history (LuxAlgo/broker-sdk#24). Once that history arrives, the journal shows three problems, all reported by @anthony-som in #28:

  • Phantom positions. Selling shares bought before the history starts shows up as a short that never existed.
  • Expired options. An option that expired while held stays open forever, because Webull records no fill for the expiry.
  • Option P&L. Option P&L uses a multiplier of 1, because contract sizes only came from settings.

Fix

  • History limit. keepWithinHistory in apps/web/src/server/broker-history.ts is a pure step that decides how much of each new fill to keep.
    • A close with nothing open is dropped.
    • A close bigger than what the history opened keeps only the part the history covers (sell 3 against 1 keeps 1). That books the real P&L of anything bought inside the history.
    • For fills Webull doesn't label as opening or closing, its complete equity position list decides which fill opened a position that never existed.
    • The kept part of a fill hashes with the broker's quantity (hashQuantity), so later syncs still match it.
  • Expired options. An option that expired while held closes at 0 at the 4pm New York expiry, without default fees. The fixed time gives it the same hash on every sync.
  • Contract sizes. Webull's option contract sizes are saved as multipliers unless you set one. Synced fills keep the broker's asset class.
  • Later syncs. They pass historySince, the last sync less 30 days, so only recent orders are fetched. On the test account in Webull sync: connection fails, no trades import, and synced history creates phantom positions #28 that brought a repeat sync from about 75s down to about 1s.

Limits, noted in code:

  • An option exercised or assigned in the money also closes at 0.
  • A real flip the broker's list agrees with (sell 3 against 2 bought before the history, leaving a short of 1) keeps all 3.

Test

  • apps/web/tests/broker-history.test.ts has unit tests for:
    • sales of shares from before the history;
    • closes cut back to the part the history covers, including when an earlier sync stored the buy;
    • labeled option closes;
    • flips the broker confirms;
    • groups replaying apart;
    • expiries in summer and winter.
  • apps/web/tests/webull-sync-flow.test.ts runs syncAccount with broker-sdk's Webull adapter against a stubbed gateway. It covers:
    • a sale of shares from before the history;
    • a close partly beyond it that stays put on later syncs;
    • identical orders in one second;
    • an option expiring while held, priced with its contract size.

Checks run locally

All of these pass: pnpm format:check, pnpm typecheck, pnpm test (70 files, 658 tests), node scripts/check-licenses.mjs, pnpm -r --filter "./packages/*" build and pnpm build.

Fixes #28

broker-sdk now reads Webull's order history (a year of it). Journaling
that history needs three things the journal didn't do.

- Fills that reach back before the start of a broker's history are
  handled in a pure step, keepWithinHistory. A close with nothing open
  is dropped. A close bigger than what the history opened keeps the
  part the history covers. For unlabeled fills, Webull's complete
  equity position list decides which fill opened a position that never
  existed. The kept part of a fill hashes with the broker's quantity
  (hashQuantity), so later syncs still match it.
- Options that expired while held close at 0 at the 4pm New York
  expiry. Webull records no fill for an expiry, so they otherwise stay
  open forever.
- Broker-stated option contract sizes are saved as multipliers unless
  the user set one, and synced fills keep the broker's asset class.
- Later syncs pass historySince (the last sync less 30 days), so only
  recent orders are fetched.

Replaces #29; thanks to @anthony-som for the proposal.
0.6.0 adds Webull order history and the trade fields this branch uses
(LuxAlgo/broker-sdk#24), plus Binance USDⓈ-M futures
(LuxAlgo/broker-sdk#25).
@ChristopherDownie
ChristopherDownie marked this pull request as ready for review October 27, 2026 00:48
@ChristopherDownie
ChristopherDownie merged commit ea98f8a into main Oct 27, 2026
1 check passed
@ChristopherDownie
ChristopherDownie deleted the fix/webull-sync branch October 28, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Webull sync: connection fails, no trades import, and synced history creates phantom positions

1 participant